.\"***************************************************************************
.\" Copyright 2018-2023,2024 Thomas E. Dickey                                *
.\" Copyright 1998-2016,2017 Free Software Foundation, Inc.                  *
.\"                                                                          *
.\" Permission is hereby granted, free of charge, to any person obtaining a  *
.\" copy of this software and associated documentation files (the            *
.\" "Software"), to deal in the Software without restriction, including      *
.\" without limitation the rights to use, copy, modify, merge, publish,      *
.\" distribute, distribute with modifications, sublicense, and/or sell       *
.\" copies of the Software, and to permit persons to whom the Software is    *
.\" furnished to do so, subject to the following conditions:                 *
.\"                                                                          *
.\" The above copyright notice and this permission notice shall be included  *
.\" in all copies or substantial portions of the Software.                   *
.\"                                                                          *
.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS  *
.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF               *
.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.   *
.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,   *
.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR    *
.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR    *
.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE.                               *
.\"                                                                          *
.\" Except as contained in this notice, the name(s) of the above copyright   *
.\" holders shall not be used in advertising or otherwise to promote the     *
.\" sale, use or other dealings in this Software without prior written       *
.\" authorization.                                                           *
.\"***************************************************************************
.\"
.\" $Id: curs_initscr.3x,v 1.79 2024/09/21 17:59:36 tom Exp $
.TH initscr 3NCURSES 2024-09-21 "ncurses 6.5" "Library calls"
.ie \n(.g \{\
.ds `` \(lq
.ds '' \(rq
.\}
.el \{\
.ie t .ds `` ``
.el   .ds `` ""
.ie t .ds '' ''
.el   .ds '' ""
.\}
.
.de bP
.ie n  .IP \(bu 4
.el    .IP \(bu 2
..
.SH NAME
\fB\%initscr\fP,
\fB\%newterm\fP,
\fB\%endwin\fP,
\fB\%isendwin\fP,
\fB\%set_term\fP,
\fB\%delscreen\fP \-
initialize, manipulate, or tear down \fIcurses\fR terminal interface
.SH SYNOPSIS
.nf
\fB#include <ncursesw/curses.h>
.PP
\fBWINDOW * initscr(void);
\fBint endwin(void);
.PP
\fBbool isendwin(void);
.PP
\fBSCREEN * newterm(const char * \fItype\fP, FILE * \fIoutf\fP, FILE * \fIinf\fP);
\fBSCREEN * set_term(SCREEN * \fInew\fP);
\fBvoid delscreen(SCREEN * \fIsp\fP);
.fi
.SH DESCRIPTION
.SS initscr
.B \%initscr
determines the terminal type and initializes the library's
.IR SCREEN ","
.IR WINDOW ","
and other data structures.
It is normally the first
.I curses
function call a program performs.
However,
an application with unusual needs might employ a few other
.I curses
functions beforehand:
.bP
\fB\%slk_init\fP(3NCURSES) to set up soft-label keys;
.bP
\fB\%filter\fP(3NCURSES) if the program is designed to operate in a process
pipeline;
.bP
\fB\%ripoffline\fP(3NCURSES) to reserve up to five lines at the top and/or
bottom of the screen from management by
.BR \%stdscr ","
the standard
.I curses
window;
and
.bP
\fB\%use_env\fP(3NCURSES) and/or \fB\%use_tioctl\fP(3NCURSES) to configure use of
the process environment and operating system's terminal driver,
respectively,
when determining the dimensions of the terminal display.
.PP
Further,
a
.I curses
program might call
.B \%newterm
prior to or instead of
.B \%initscr
in two specialized cases described in its subsection below.
.PP
.B \%initscr
causes the first \fB\%refresh\fP(3NCURSES) call to clear the screen.
If errors occur,
.B \%initscr
writes an appropriate diagnostic message to the standard error stream
and exits;
otherwise,
it returns a pointer to
.BR stdscr "."
.SS newterm
An application that manages multiple terminals should call
.B \%newterm
once for each such device
.I instead
of
.BR \%initscr "."
.BR \%newterm 's
arguments are
.bP
the
.I type
of the associated terminal,
or
.I NULL
to use the
.I TERM
environment variable;
.bP
an output stream
.I outf
connected to the terminal;
and
.bP
an input stream
.I inf
connected to the terminal.
It returns a variable of structure type
.I SCREEN
.BR * ","
which should be saved for later use with
.B \%set_term
and
.BR \%delscreen "."
.PP
.B \%newterm
passes the file descriptor of the output stream to the
.I \%term\%info
function \fB\%setupterm\fP(3NCURSES),
which returns a pointer to a
.I \%TERMINAL
structure that
.B \%newterm
stores in the
.I SCREEN
it returns to the application.
.PP
An application that needs to inspect a terminal type's capabilities,
so that it can continue to run in a line-oriented mode
if the terminal cannot support a screen-oriented program,
would also use
.BR \%newterm "."
If at most one terminal connection is needed,
the programmer could perform such a capability test,
decide which mode in which to operate,
then call
.B \%delscreen
on the pointer returned by
.BR \%newterm ","
and proceed with either
.B \%initscr
or a
.RI non- curses
interface.
.SS endwin
The program must also call
.B \%endwin
for each terminal being used before exiting from
.IR curses "."
If
.B \%newterm
is called more than once for the same terminal,
the first terminal referred to must be the last one for which
.B \%endwin
is called.
.PP
A program should always call
.B \%endwin
before exiting the application
or temporarily suspending
.IR curses "'s"
management of the terminal.
.BR \%endwin ":"
.bP
resets colors to correspond with the default color pair 0,
.bP
moves the cursor to the lower left-hand corner of the screen,
.bP
clears the remainder of the line so that it uses the default colors,
.bP
sets the cursor to normal visibility
(see \fB\%curs_set\fP(3NCURSES)),
.bP
if applicable,
stops cursor-addressing mode using the
.B \%exit_ca_mode
.RB \%( rmcup )
terminal capability,
and
.bP
restores terminal modes (see \fB\%reset_shell_mode\fP(3NCURSES)).
.PP
Calling \fB\%refresh\fP(3NCURSES) or \fB\%doupdate\fP(3NCURSES) after a
temporary escape causes
.I curses
to resume managing the terminal.
.SS isendwin
.B \%isendwin
returns
.B TRUE
if
.B \%endwin
has been called without any subsequent calls to \fB\%wrefresh\fP(3NCURSES),
and
.B FALSE
otherwise.
.SS set_term
.B \%set_term
re-orients the
.I curses
library's operations to another terminal
when the application has arranged to manage more than one with
.BR \%newterm "."
.B \%set_term
expects a
.I SCREEN
pointer previously returned by
.B \%newterm
as an argument,
and returns the previous one.
.B \%set_term
is the only
.I curses
API function that manipulates
.I SCREEN
pointers;
all others affect only the current terminal.
.SS delscreen
.B \%delscreen
frees the storage backing the supplied
.I SCREEN
pointer argument.
.B \%endwin
does not,
so that an application can resume managing a terminal with
.I curses
after a
(possibly conditional or temporary)
suspension;
see \fB\%kernel\fP(3NCURSES).
Call
.B \%delscreen
after
.B \%endwin
when a particular
.I SCREEN
structure
is no longer needed.
.SH RETURN VALUE
.B \%endwin
returns
.B OK
on success and
.B ERR
on failure.
.PP
In
.IR \%ncurses ","
.bP
.B \%endwin
returns
.B ERR
if
.RS
.bP
the terminal was not initialized,
.bP
.B \%endwin
is called more than once without updating the screen,
or
.bP
\fB\%reset_shell_mode\fP(3NCURSES) returns
.BR ERR "."
.RE
.bP
.B \%newterm
returns
.B ERR
if it cannot allocate storage for the
.I SCREEN
data structure
or the top-level windows thereof:
.BR \%curscr ","
.BR \%newscr ","
and
.BR \%stdscr "."
.PP
Functions that return pointers return
.I NULL
on error.
In
.IR \%ncurses ","
.B \%set_term
does not fail.
.SH PORTABILITY
X/Open Curses,
Issue 4 describes these functions.
It specifies no error conditions for them.
.SS Differences
X/Open Curses specifies that portable applications must not
call \fB\%initscr\fP more than once:
.bP
The portable way to use \fB\%initscr\fP is once only,
using \fB\%refresh\fP(3NCURSES)
to restore the screen after \fB\%endwin\fP.
.bP
This implementation allows using \fB\%initscr\fP after \fB\%endwin\fP.
.PP
Old versions of curses, e.g., BSD 4.4, would return a null pointer
from \fB\%initscr\fP when an error is detected, rather than exiting.
It is safe but redundant to check the return value of \fB\%initscr\fP
in X/Open Curses.
.PP
Calling \fB\%endwin\fP does not dispose of the memory allocated in
\fB\%initscr\fP or \fB\%newterm\fP.
Deleting a \fISCREEN\fP provides a way to do this:
.bP
X/Open Curses does not say what happens to \fI\%WINDOW\fPs when
\fB\%delscreen\fP
\*(``frees storage associated with the \fISCREEN\fP\*(''
nor does the SVr4 documentation help,
adding that it should be called after \fB\%endwin\fP if a \fISCREEN\fP
is no longer needed.
.bP
However, \fI\%WINDOW\fPs are implicitly associated with a \fISCREEN\fP.
so that it is reasonable to expect \fB\%delscreen\fP to deal with these.
.bP
SVr4 curses deletes the standard \fI\%WINDOW\fP structures
\fB\%stdscr\fP and \fB\%curscr\fP as well as a work area \fB\%newscr\fP.
SVr4 curses ignores other windows.
.bP
Since version 4.0 (1996),
\fI\%ncurses\fP has maintained a list of all windows for each screen,
using that information to delete those windows when \fB\%delscreen\fP is
called.
.bP
NetBSD copied this feature of \fI\%ncurses\fP in 2001.
PDCurses follows the SVr4 model,
deleting only the standard \fI\%WINDOW\fP structures.
.SS "High-level versus Low-level"
Different implementations may disagree regarding the level of some functions.
For example, \fISCREEN\fP (returned by \fB\%newterm\fP) and
\fI\%TERMINAL\fP (returned by \fB\%setupterm\fP(3NCURSES)) hold file
descriptors for the output stream.
If an application switches screens using \fB\%set_term\fR,
or switches terminals using \fB\%set_curterm\fP(3NCURSES),
applications which use the output file descriptor can have different
behavior depending on which structure holds the corresponding descriptor.
.bP
NetBSD's
.I \%baudrate
function uses the descriptor in
.IR \%TERMINAL "."
.I \%ncurses
and SVr4
.I curses
use the descriptor in
.IR SCREEN "."
.bP
NetBSD and \fI\%ncurses\fP use the descriptor
in \fI\%TERMINAL\fP
for terminal I/O modes,
e.g.,
\fB\%def_shell_mode\fP(3NCURSES),
\fB\%def_prog_mode\fP(3NCURSES).
SVr4 curses uses the descriptor in \fISCREEN\fP.
.SS "Unset \f(BITERM\fP Variable"
If the \fITERM\fP variable is missing or empty, \fB\%initscr\fP uses the
value \*(``unknown\*('',
which normally corresponds to a terminal entry with the
.B \%generic
.RB ( gn )
capability.
Generic entries are detected by \fB\%setupterm\fP(3NCURSES)
and cannot be used for full-screen operation.
Other implementations may handle
a missing/empty \fITERM\fP variable differently.
.SS "Signal Handlers"
Quoting from X/Open Curses Issue 7, section 3.1.1:
.RS 5
.PP
Curses implementations may provide for special handling of the
\%SIGINT,
\%SIGQUIT,
and \%SIGTSTP signals if their disposition is \%SIG_DFL at the time
.I \%initscr
is called.\|.\|.
.PP
Any special handling for these signals may remain in effect for the
life of the process or until the process changes the disposition of
the signal.
.PP
None of the Curses functions are required to be safe
with respect to signals.\|.\|.
.RE
.PP
This implementation establishes signal handlers during initialization,
e.g., \fB\%initscr\fP or \fB\%newterm\fP.
Applications which must handle these signals should set up the corresponding
handlers \fIafter\fP initializing the library:
.TP 5
.B SIGINT
The handler \fIattempts\fP to clean up the screen on exit.
Although it \fIusually\fP works as expected, there are limitations:
.RS 5
.bP
Walking the \fISCREEN\fP list is unsafe, since all list management
is done without any signal blocking.
.bP
On systems which have \fB\%REENTRANT\fP turned on, \fB\%set_term\fP uses
functions which could deadlock or misbehave in other ways.
.bP
\fB\%endwin\fP calls other functions,
many of which use \fI\%stdio\fP(3) or other library functions which are
clearly unsafe.
.RE
.TP 5
.B SIGTERM
This uses the same handler as \fB\%SIGINT\fP, with the same limitations.
It is not mentioned in X/Open Curses, but is more suitable for this
purpose than \fB\%SIGQUIT\fP (which is used in debugging).
.TP 5
.B SIGTSTP
This handles the \fIstop\fP signal, used in job control.
When resuming the process, this implementation discards pending
input with \fB\%flushinp\fP(3NCURSES), and repaints the screen
assuming that it has been completely altered.
It also updates the saved terminal modes with
\fB\%def_shell_mode\fP(3NCURSES).
.TP 5
.B SIGWINCH
This handles the window-size changes which were ignored in
the standardization efforts.
The handler sets a (signal-safe) variable
that is later tested by \fB\%wgetch\fP(3NCURSES) and \fB\%wget_wch\fP(3NCURSES).
.RS
.bP
.B \%wgetch
returns the key code
.BR \%KEY_RESIZE "."
.bP
.B \%wget_wch
returns
.B \%KEY_CODE_YES
and sets its
.I wch
parameter to
.BR \%KEY_RESIZE "."
.RE
.IP
At the same time, \fI\%ncurses\fP calls \fB\%resizeterm\fP to adjust the
standard screen \fB\%stdscr\fP,
and update other data such as \fBLINES\fP and \fBCOLS\fP.
.SH SEE ALSO
\fB\%ncurses\fP(3NCURSES),
\fB\%kernel\fP(3NCURSES),
\fB\%refresh\fP(3NCURSES),
\fB\%slk\fP(3NCURSES),
\fB\%terminfo\fP(3NCURSES),
\fB\%util\fP(3NCURSES),
\fB\%curses_variables\fP(3NCURSES)
